home *** CD-ROM | disk | FTP | other *** search
/ Aminet 33 / Aminet 33 - October 1999.iso / Aminet / dev / c / GAPLib.lha / GAPLib / utility / doc / report.doc next >
Encoding:
Text File  |  1998-06-09  |  5.2 KB  |  207 lines
  1. TABLE OF CONTENTS
  2.  
  3. report/--background--
  4. report/--format--
  5. report/DoReport
  6. report/EndReport
  7. report/MakeReport
  8.  
  9.  
  10. report/--background--                                     report/--background--
  11.  
  12.    PURPOSE
  13.     To enable easy generation of data files for GAP-Lib.
  14.  
  15.    OVERVIEW
  16.     Report generation utility code for GAP-Lib.
  17.  
  18.     The report utility package consists of three functions, one to
  19.     initialize a report structure, one to write data to any report files
  20.     and one to free resources allocated by the other two functions. The
  21.     useage should be fairly obvious and the function and format
  22.     descriptions will now follow after just one further ado.
  23.  
  24.    EXAMPLE
  25.     This example outlines the useage of the report function, in this
  26.     case two report files will be generated - "example.avg" and
  27.     "example.max".
  28.  
  29.     Example code:
  30.  
  31.     #include <GAP.h>
  32.     #include "report.h"
  33.  
  34.     int main(void)
  35.     {
  36.     struct Report *Rep;
  37.     struct Population *Pop;
  38.     ...
  39.        Rep = MakeReport("example",NULL);
  40.        if(Rep!=NULL) {
  41.        ...
  42.           Pop = Evolve(Pop,Tags);
  43.           DoReport(Rep,Pop,AVERAGE|MAX);
  44.        ...
  45.           EndReport(Rep);
  46.        }
  47.     ...
  48.     }
  49.  
  50. report/--format--                                             report/--format--
  51.  
  52.    OVERVIEW
  53.     The data format output by DoReport() is indeed very simple. It consists
  54.     of two columns of data in human-readable form. The first column is the
  55.     generation and the second the data value itself. Furthermore, at the
  56.     top of each file there is a one line comment describing the content of
  57.     the columns.
  58.        The reason for choosing this format is one one hand that it is
  59.     simple to work with, and on the other hand to be compatible with
  60.     gnuplot.
  61.  
  62.    DESCRIPTION
  63.     The data format is as follows (Well, actually the format for TypeCount
  64.     is <Integer> <Integer>, but it does not hurt to treat it as double):
  65.  
  66.     #Generation, <Data>
  67.     <Integer> <Double>
  68.     ...
  69.     ...
  70.     <Integer> <Double>
  71.  
  72.    EXAMPLE
  73.     Sample datafile:
  74.  
  75.     #Generation, Average
  76.     1 28.23554
  77.     2 29.45442
  78.     3 31.13943
  79.     4 31.64233
  80.     5 31.88642
  81.     6 33.19521
  82.     7 35.16777
  83.     8 35.74699
  84.     9 36.77469
  85.     10 37.45532
  86.  
  87. report/EndReport                                               report/EndReport
  88.  
  89.    NAME
  90.     EndReport -- Free a report structure.
  91.  
  92.    SYNOPSIS
  93.     void EndReport(struct Report *);
  94.  
  95.     EndReport(Rep);
  96.  
  97.    FUNCTION
  98.     Frees all resources associated with a report structure and flushes
  99.     output. In the case of using multipass mode, no output is written
  100.     until this function is called.
  101.  
  102.    INPUTS
  103.     Rep    - The report structure to be deallocated.
  104.  
  105.    RESULT
  106.     None.
  107.  
  108.    BUGS
  109.     None known.
  110.  
  111.    SEE ALSO
  112.     MakeReport(), DoReport()
  113.  
  114. report/DoReport                                                 report/DoReport
  115.  
  116.    NAME
  117.     DoReport -- Write report data from a population structure.
  118.  
  119.    SYNOPSIS
  120.     void DoReport(struct Report *,struct Population *,unsigned long int);
  121.  
  122.     DoReport(Rep,Pop,Flags);
  123.  
  124.    FUNCTION
  125.     Writes poulation data to a set of report files.
  126.  
  127.    INPUTS
  128.     Rep    - The report structure in question.
  129.     Pop    - The population to retrieve the data from.
  130.     Flags    - A set of flags which determine which data to write.
  131.           Available flags are:
  132.  
  133.            AVERAGE   - Average fitness.
  134.            MEDIAN    - Median fitness.
  135.            TYPECOUNT - Count of most common fitness value.
  136.            STDDEV    - Standard Deviation.
  137.            MAX       - Maximum fitness.
  138.            MIN       - Minimum fitness.
  139.            ALL       - All the above.
  140.  
  141.           Flags are combined by OR:ing them together and e.g.
  142.           AVERAGE|MAX would mean write average and maximum fitness
  143.           to the report files.
  144.  
  145.    RESULT
  146.     None.
  147.  
  148.    BUGS
  149.     None known.
  150.  
  151.    SEE ALSO
  152.     MakeReport(), EndReport()
  153.  
  154.  
  155. report/MakeReport                                             report/MakeReport
  156.  
  157.    NAME
  158.     MakeReport -- Initialize a report structure and return it.
  159.     MakeReportT -- Varargs interface to MakeReport.
  160.  
  161.    SYNOPSIS
  162.     struct Report *MakeReport(char *,struct TagItem *);
  163.     struct Report *MakeReportT(char *,...);
  164.  
  165.     Rep = MakeReport(Basename,TagList);
  166.     Rep = MakeReport(Basename,...);
  167.  
  168.    FUNCTION
  169.     This function will initialize a report structure and open
  170.     report files for writing. Basename is the first part of the
  171.     filenames used for the data. The actual filenames are formed by
  172.     appending a suitable suffix to the basename such as ".max" for
  173.     maximum fitness data.
  174.  
  175.    TAGS
  176.     REP_Multipass - (BOOL) Enables or disabled multipass mode. In
  177.          multipass mode all values are stored in memory and the
  178.          average over all runs are written when EndReport() is
  179.          called. To envable multipass mode, one must also provide
  180.          REP_Generations. Multipass mode uses substantially more
  181.          memory than singlepass mode.
  182.  
  183.     REP_Generations - (int) Sets the number of generations in each
  184.          pass for multipass mode.
  185.  
  186.     REP_Indexed - (BOOL) Usually, old reports are overwritten when
  187.          running a program again. With this flag set to TRUE, every
  188.          report will have an index from 0 to MAX_INDEX as defined in
  189.          report.c (Currently 2048). The correct index is determined
  190.          at run time and is the highest free index. An index is
  191.          considered available if there is no file with the same
  192.          basename and index regardless of extension.
  193.  
  194.    INPUTS
  195.     Basename   - The main part of the names of the report files.
  196.     TagList    - Options to MakeReport().
  197.  
  198.    RESULT
  199.     An initialized report structure or NULL if an error occured.
  200.  
  201.    BUGS
  202.     None known.
  203.  
  204.    SEE ALSO
  205.     DoReport(), EndReport()
  206.  
  207.